// Copyright (c) 2011 The LevelDB Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file. See the AUTHORS file for names of contributors.

#ifndef STORAGE_LEVELDB_INCLUDE_OPTIONS_H_
#define STORAGE_LEVELDB_INCLUDE_OPTIONS_H_

#include <cstddef>

#include "leveldb/export.h"

namespace leveldb {

class Cache;
class Comparator;
class Env;
class FilterPolicy;
class Logger;
class Snapshot;

// DB contents are stored in a set of blocks, each of which holds a
// sequence of key,value pairs.  Each block may be compressed before
// being stored in a file.  The following enum describes which
// compression method (if any) is used to compress a block.
enum CompressionType {
  // NOTE: do not change the values of existing entries, as these are
  // part of the persistent format on disk.
  kNoCompression = 0x0,
  kSnappyCompression = 0x1,
  kZstdCompression = 0x2,
};

// Options to control the behavior of a database (passed to DB::Open)
struct LEVELDB_EXPORT Options {
  // Create an Options object with default values for all fields.
  Options();

  // -------------------
  // Parameters that affect behavior

  // Comparator used to define the order of keys in the table.
  // Default: a comparator that uses lexicographic byte-wise ordering
  //
  // REQUIRES: The client must ensure that the comparator supplied
  // here has the same name and orders keys *exactly* the same as the
  // comparator provided to previous open calls on the same DB.
  // 
  /*
   * 比较器，用于定义table中key按照何种规则进行排序。
   * 如果不对这个参数进行指定，则默认按照字典顺序的比较器定义，即使用BytewiseComparatorImpl。
   * 在实际调用时，客户端需要保证排序时所使用的comparator与数据库进行Open操作时传入的comparator名字相同。
   */
  const Comparator* comparator;

  // If true, the database will be created if it is missing.
  // 默认为false，如果设置为true，表示当数据库不存在时，如果调用Open方法则创建新的数据库。
  bool create_if_missing = false;

  // If true, an error is raised if the database already exists.
  // 默认为false，如果设置为true，则在进行Open操作时，首先判断该数据库是否存在，如果存在则触发一个错误。
  bool error_if_exists = false;

  // If true, the implementation will do aggressive checking of the
  // data it is processing and will stop early if it detects any
  // errors.  This may have unforeseen ramifications: for example, a
  // corruption of one DB entry may cause a large number of entries to
  // become unreadable or for the entire DB to become unopenable.
  // 默认为false。如果设置为true，将会对数据进行大量的检测工作，如果检测到任何错误，则会停止检测。这样会造成某些不可预见的后果，例如数据库中的某一个数据实体的错误将造成大量的数据实体不可读，或整个数据库不能打开。
  bool paranoid_checks = false;

  // Use the specified object to interact with the environment,
  // e.g. to read/write files, schedule background work, etc.
  // Default: Env::Default()
  // 环境变量，主要用于与系统环境进行交互，如读文件、写文件、调度后台线程任务等。Env的默认值为Env::Default()。
  Env* env;

  // Any internal progress/error information generated by the db will
  // be written to info_log if it is non-null, or to a file stored
  // in the same directory as the DB contents if info_log is null.
  // 如果不为NULL，则运行时产生的中间过程或错误信息会被写入到info_log中；如果为NULL，则会将这些信息存储在与DB相同路径下的目录中。
  Logger* info_log = nullptr;

  // -------------------
  // Parameters that affect performance

  // Amount of data to build up in memory (backed by an unsorted log
  // on disk) before converting to a sorted on-disk file.
  //
  // Larger values increase performance, especially during bulk loads.
  // Up to two write buffers may be held in memory at the same time,
  // so you may wish to adjust this parameter to control memory usage.
  // Also, a larger write buffer will result in a longer recovery time
  // the next time the database is opened.
  // 内存中将要写入到硬盘文件（sorted on-disk file）的数据量大小，默认为4MB。
  // 该参数增大，则会提升性能，特别是在大量加载的场景中。内存中最多同时保存2个写缓存。
  // 此外，写缓存越大，则DB在下次打开过程中恢复的时间越长。
  size_t write_buffer_size = 4 * 1024 * 1024;

  // Number of open files that can be used by the DB.  You may need to
  // increase this if your database has a large working set (budget
  // one open file per 2MB of working set).
  // write_buffer_size
  // DB所能使用的最大打开文件数。如果在应用场景中有一个大的数据集，则可以增大该参数。该参数默认为1000。
  // 如果数据库的工作集较大（即需要频繁读写的数据量较大），则可能需要增加 max_open_files 的值。根据常规经验，建议每 2MB 工作集预留一个打开文件的资源预算。因此，如果工作集大小为 100MB，则建议将 max_open_files 设置为 50。 
  int max_open_files = 1000;

  // Control over blocks (user data is stored in a set of blocks, and
  // a block is the unit of reading from disk).

  // If non-null, use the specified cache for blocks.
  // If null, leveldb will automatically create and use an 8MB internal cache.
  // block是从硬盘上读数据的单位，用户的数据就存储在许多block中。
  // 默认为NULL，LevelDB自动创建并使用8MB的缓存。
  // 如果不为空，则由用户指定相对应的block缓存。
  Cache* block_cache = nullptr;

  // Approximate size of user data packed per block.  Note that the
  // block size specified here corresponds to uncompressed data.  The
  // actual size of the unit read from disk may be smaller if
  // compression is enabled.  This parameter can be changed dynamically.
  // 用户数据每一个block的大小，默认为4KB。
  // block size参数针对的是没有压缩的数据。如果使用了压缩功能，则实际每个单位block从硬盘中读取的数据大小可能会较小。这个参数可以进行动态修改。
  size_t block_size = 4 * 1024;

  // Number of keys between restart points for delta encoding of keys.
  // This parameter can be changed dynamically.  Most clients should
  // leave this parameter alone.
  // 用于设置块重启点之间的键数。
  // 块是存储键值对的最小单位，在磁盘中以一个文件为单位进行存储。每个块内部会采用一种基于差分编码的方式对键进行压缩，以减少存储空间。
  // 在差分编码的实现中，每个块内通常包含多个重启点（restart point），重启点是一个特殊的键，表示从该位置开始进行全量编码（不再使用差分编码）。这样做的好处是可以快速地跳过许多键值对，直接找到需要的位置，从而提高读取性能。
  // 块内键的差分编码和重启点的设置，是通过 block_restart_interval 参数来控制的。具体来说，该参数指定了相邻两个重启点之间的键的数量。例如，如果 block_restart_interval=16，则表示每 16 个键设置一个重启点。
  // 对于块内的任何键值对，其编码方式都是相同的：首先计算与前一个键的差量，然后将差量和值存储到块中。因此，如果当前键离上一个重启点很远，则需要在读取时依次解码所有的键值对，直到找到需要的位置。这样做显然会影响读取性能和存储空间。
  // 设置重启点的好处是可以减少需要解码的键值对数量，从而提高读取性能。但同时也会增加存储空间，因为每个重启点需要存储一个全量的键值对，且重启点之间的差量较小，无法进行较好的压缩。因此，在设置 block_restart_interval 的时候需要权衡存储空间和读取性能的关系，根据实际需求进行调整。
  int block_restart_interval = 16;

  // Leveldb will write up to this amount of bytes to a file before
  // switching to a new one.
  // Most clients should leave this parameter alone.  However if your
  // filesystem is more efficient with larger files, you could
  // consider increasing the value.  The downside will be longer
  // compactions and hence longer latency/performance hiccups.
  // Another reason to increase this parameter might be when you are
  // initially populating a large database.
  // 默认为2MB。指定LevelDB向一个文件写入字节的最大值。
  // 一般用户不需要关注这个参数。
  // 然而，如果用户的文件系统可以支持大的文件，可以考虑增大该参数值。
  // 但增大该参数，会增加压缩与等待间隔的时间。
  // 如果你本身就需要操作一个大数据库，也可以适当增大该参数值。
  size_t max_file_size = 2 * 1024 * 1024;

  // Compress blocks using the specified compression algorithm.  This
  // parameter can be changed dynamically.
  //
  // Default: kSnappyCompression, which gives lightweight but fast
  // compression.
  //
  // Typical speeds of kSnappyCompression on an Intel(R) Core(TM)2 2.4GHz:
  //    ~200-500MB/s compression
  //    ~400-800MB/s decompression
  // Note that these speeds are significantly faster than most
  // persistent storage speeds, and therefore it is typically never
  // worth switching to kNoCompression.  Even if the input data is
  // incompressible, the kSnappyCompression implementation will
  // efficiently detect that and will switch to uncompressed mode.
  // 压缩算法类型，影响读写性能和存储空间。
  CompressionType compression = kSnappyCompression;

  // Compression level for zstd.
  // Currently only the range [-5,22] is supported. Default is 1.
  // Zstandard 压缩算法的压缩级别，介于 -5 和 22 之间，默认值为1。
  int zstd_compression_level = 1;

  // EXPERIMENTAL: If true, append to existing MANIFEST and log files
  // when a database is opened.  This can significantly speed up open.
  //
  // Default: currently false, but may become true later.
  // 该变量用于控制是否在打开数据库时追加到现有的 MANIFEST 和日志文件中，以加快数据库打开速度。
  // 在默认情况下，当打开一个已存在的数据库时，LevelDB 会创建新的 MANIFEST 和日志文件，并依次读取和重放这些文件中的所有操作记录。如果数据库非常大（例如几百GB或几TB），则这个过程可能需要较长时间，占用大量的 CPU 和磁盘资源，从而影响应用程序的性能。
  // 为了解决这个问题，可以将 reuse_logs 设置为 true，在打开数据库时尝试直接使用现有的 MANIFEST 和日志文件，而不是创建新的文件。这样做可以避免读取和重放之前的操作记录，从而显著提高数据库打开速度，减少资源占用。
  // 需要注意的是，由于 reuse_logs 是实验性功能，可能会存在一些潜在的问题，如数据丢失、损坏等，因此建议在使用前先进行测试和评估。此外，该功能目前处于关闭状态，但未来可能会默认开启。
  bool reuse_logs = false;

  // If non-null, use the specified filter policy to reduce disk reads.
  // Many applications will benefit from passing the result of
  // NewBloomFilterPolicy() here.
  // 该变量用于设置过滤策略，以减少磁盘读取次数和提高读取性能。
  // 在 LevelDB 中，为了加快数据的查找速度，通常会在内存中维护一个键值对的索引结构，称为 MemTable。当 MemTable 达到一定大小后，LevelDB 会将其转化为一个或多个磁盘上的 SSTable（Sorted String Table），并使用一个元数据文件 MANIFEST 记录这些 SSTable 的信息。在查询时，LevelDB 需要根据给定的键值，在 MANIFEST 和 SSTable 中进行查找，以确定相应的值。
  // 由于 SSTable 是顺序存储的，因此可以采用预读取的方式进行优化，即一次读取多个块到缓存中，从而减少磁盘读取次数，并提高读取性能。但是，如果查询的键值不存在于 SSTable 中，则需要遍历整个 SSTable 才能确定，这可能会导致大量的磁盘读取操作，降低查询性能。
  // 为了解决这个问题，LevelDB 引入了 Bloom Filter 的概念。Bloom Filter 是一种空间效率很高的随机数据结构，可用于检测一个元素是否属于一个集合。它的特点是可以快速地判断一个键值是否可能存在于 SSTable 中，从而避免不必要的磁盘读取操作。
  // 在 LevelDB 中，可以通过设置 filter_policy 参数来指定使用哪种过滤策略，默认值为 NULL，表示不使用过滤器。如果需要使用过滤器，可以传入一个自定义的过滤器对象，或者使用 LevelDB 提供的默认过滤器 NewBloomFilterPolicy()。后者使用 Bloom Filter 作为底层实现，可以有效地减少磁盘读取次数，并提高查询性能。
  const FilterPolicy* filter_policy = nullptr;
};

// Options that control read operations
struct LEVELDB_EXPORT ReadOptions {
  // If true, all data read from underlying storage will be
  // verified against corresponding checksums.
  // 如果为 true，则在读取数据时会对每个数据块的校验和进行验证，以确保数据的一致性。
  // 默认情况下为 false，即不进行校验和验证。
  bool verify_checksums = false;

  // Should the data read for this iteration be cached in memory?
  // Callers may wish to set this field to false for bulk scans.
  // 是否将读取到的数据缓存在 LevelDB 的缓存中。当需要多次访问同一数据时，开启此选项可以提高读取性能。
  // 但是，对于一些扫描大量数据的操作，可能会导致缓存占用过多内存，因此有时需要将该值设置为 false。
  bool fill_cache = true;

  // If "snapshot" is non-null, read as of the supplied snapshot
  // (which must belong to the DB that is being read and which must
  // not have been released).  If "snapshot" is null, use an implicit
  // snapshot of the state at the beginning of this read operation.
  // 指定读取操作使用的快照版本。如果为 NULL，则使用当前数据库的最新状态；否则，使用指定的快照。（快照是一种轻量级的事务机制，可以避免读取期间被其他线程或进程修改数据的问题）。
  const Snapshot* snapshot = nullptr;
};

// Options that control write operations
struct LEVELDB_EXPORT WriteOptions {
  WriteOptions() = default;

  // If true, the write will be flushed from the operating system
  // buffer cache (by calling WritableFile::Sync()) before the write
  // is considered complete.  If this flag is true, writes will be
  // slower.
  //
  // If this flag is false, and the machine crashes, some recent
  // writes may be lost.  Note that if it is just the process that
  // crashes (i.e., the machine does not reboot), no writes will be
  // lost even if sync==false.
  //
  // In other words, a DB write with sync==false has similar
  // crash semantics as the "write()" system call.  A DB write
  // with sync==true has similar crash semantics to a "write()"
  // system call followed by "fsync()".
  // 如果为 true，则在写入完成后会调用 WritableFile::Sync() 方法将数据刷到文件系统缓存中，以确保数据持久化。
  // 如果为 false，则不进行同步，写入速度更快，但如果机器崩溃，则有可能丢失部分数据。
  // 需要注意的是，如果只是进程崩溃而不是整个机器重启，则即使 sync=false，也不会丢失任何写入的数据。
  bool sync = false;
};

}  // namespace leveldb

#endif  // STORAGE_LEVELDB_INCLUDE_OPTIONS_H_
